Multi-Version PostgreSQL Support Implementation

This PR implements a comprehensive multi-version PostgreSQL support system for libpg-query-node with a folder-based structure, enabling users to choose between lightweight and full-featured packages based on their needs.

🎯 Overview

• Lightweight versions (PG13-16): Parse, fingerprint, normalize, PL/pgSQL only
• Full version (PG17): Complete functionality including deparse and scan
• Multi-version package: Runtime version selection with PG15/16/17 support
• Master build system: Coordinated builds across all versions

📦 Package Structure

libpg-query-13/          # PostgreSQL 13 (lightweight)
libpg-query-14/          # PostgreSQL 14 (lightweight)
libpg-query-15/          # PostgreSQL 15 (lightweight)
libpg-query-16/          # PostgreSQL 16 (lightweight)
libpg-query-full/        # PostgreSQL 17 (full functionality)
libpg-query-multi/       # Multi-version with runtime selection
Makefile                 # Master build coordinator

🚀 Key Features

Lightweight Versions (PG13-16)

• Excluded functions: wasm_deparse_protobuf, wasm_scan, wasm_parse_query_protobuf, wasm_get_protobuf_len
• Smaller bundle size: ~1-2MB vs ~5-6MB for full version
• Core functionality: Parse, fingerprint, normalize, PL/pgSQL parsing
• No proto.js dependency: Reduces package size significantly

Full Version (PG17)

• Complete functionality: All PostgreSQL 17 features
• Deparse support: Convert AST back to SQL
• Scan support: Token-level query analysis
• Proto.js included: For deparse operations

Multi-Version Package

• Runtime version selection: new Parser({ version: 15 })
• Automatic feature detection: Helpful error messages for unavailable features
• Named exports: Direct access to version-specific functions
• Type generation: Version-specific TypeScript definitions

🔧 Technical Implementation

WASM Wrapper Modifications

• Created wasm_wrapper_light.c for lightweight versions
• Excluded deparse and scan functions from lightweight builds
• Maintained full compatibility for existing functionality

JavaScript API Changes

• Removed deparse/scan exports from lightweight versions
• Created Parser class with version selection logic
• Added error handling for unavailable features

Build System

• Version-specific Makefiles: Each package has its own build configuration
• Master Makefile: Coordinates builds across all versions
• Emscripten exports: Customized for each version's functionality

Type Generation

• PgProtoParser integration: Generates types from GitHub proto files
• Version-specific URLs: https://raw.githubusercontent.com/pganalyze/libpg_query/refs/tags/{VERSION}/protobuf/pg_query.proto
• Replaces @pgsql/types: For multi-version package

📋 Version Tags Used

• PostgreSQL 13: 13-2.2.0
• PostgreSQL 14: 14-3.0.0
• PostgreSQL 15: 15-4.2.4
• PostgreSQL 16: 16-5.2.0
• PostgreSQL 17: 17-6.1.0

🧪 Testing Strategy

• Version-specific test suites: Each package maintains its own tests
• Feature restriction tests: Verify lightweight versions exclude deparse/scan
• Parser class tests: Multi-version functionality and error handling
• Cross-version compatibility: Ensure consistent API behavior

📊 Bundle Size Comparison

🔨 Build Commands

# Build all packages
EMSCRIPTEN=1 make build-all

# Build specific types
EMSCRIPTEN=1 make build-lightweight  # PG13-16
EMSCRIPTEN=1 make build-full         # PG17
EMSCRIPTEN=1 make build-multi        # Multi-version

# Install dependencies and test
make install-deps
make test-all

📖 Usage Examples

Lightweight Version

import { parse, fingerprint } from 'libpg-query-15';
const ast = await parse('SELECT * FROM users');
const fp = await fingerprint('SELECT * FROM users WHERE id = $1');

Full Version

import { parse, deparse, scan } from 'libpg-query-full';
const ast = await parse('SELECT * FROM users');
const sql = await deparse(ast);
const tokens = await scan('SELECT * FROM users');

Multi-Version

import { Parser } from 'libpg-query-multi';

// Default to PG17
const parser = new Parser();
const result = await parser.parse('SELECT * FROM users');

// Specify version
const pg15Parser = new Parser({ version: 15 });
const result15 = await pg15Parser.parse('SELECT * FROM users');

// Feature availability handling
try {
  await pg15Parser.deparse(result15); // Throws helpful error
} catch (error) {
  console.log(error.message); // "Deparse not available for PostgreSQL 15"
}

✅ Verification

• All packages build successfully with EMSCRIPTEN
• Lightweight versions exclude deparse/scan functions
• Parser class API works with version selection
• Test suites pass for all packages
• TypeScript definitions generated correctly
• Master Makefile coordinates builds properly
• Bundle sizes optimized for lightweight versions

🔗 Related

• Addresses multi-version PostgreSQL support requirements
• Maintains backward compatibility with existing API
• Provides migration path for users needing specific versions
• Enables bundle size optimization for production deployments

Link to Devin run: https://app.devin.ai/sessions/fc97aafda04f4867810ec991fb0efd2c
Requested by: Dan Lynch ([email protected])